home *** CD-ROM | disk | FTP | other *** search
/ BBS Toolkit / BBS Toolkit.iso / programs / znews093.zip / ZIPNEWS.DOC < prev    next >
Text File  |  1993-01-20  |  18KB  |  360 lines

  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.                             ZipNews v0.93ß (1/20/93)
  8.  
  9.                  (c) Copyright 1993 by J.C. Kilday Associates
  10.  
  11.  
  12.                      Developed at the Northern Lights BBS
  13.  
  14.                         207-761-4782   v.32bis/VHST
  15.  
  16.  
  17.  
  18.  
  19.                                Table of Contents
  20.                                -----------------
  21.  
  22.                        Introduction ..................... 1
  23.  
  24.                        Description ...................... 2
  25.  
  26.                        Installation Overview ............ 2
  27.  
  28.                        Installation Details ............. 3
  29.  
  30.                        Operating/Using ZipNews .......... 4
  31.  
  32.                        Distribution and Restrictions .... 5
  33.  
  34.                        After You Register ZipNews ....... 5
  35.  
  36.                        Support .......................... 6
  37.  
  38.  
  39.                                  ZipNews v0.93ß                      Page 1
  40.      Introduction
  41.      ------------
  42.  
  43.      ZipNews is an external command  for use with the DOS-based  Waffle BBS
  44.      package.  It operates much like a Door in that it reacts interactively
  45.      to caller input as an extension of the BBS software.  It's purpose  is
  46.      fast delivery of Usenet news articles for offline reading.  It greatly
  47.      simplifies the process of reading  Usenet news by allowing the  caller
  48.      to download new postings in  compressed form for reading offline.   In
  49.      accomplishing  this,  ZipNews  allows  a  broad selection of DOS-based
  50.      archiving utilities for compressing the news packet and it supports  a
  51.      variety of file transfer protocols  (use of Forsberg's DSZ package  is
  52.      recommended).  The selection  of archiving utilities and  protocols is
  53.      determined  by  the  system  operator.    The  individual command line
  54.      specifications are  also established  by the  system operator  using a
  55.      configuration text file.  A  sample configuration file is included  in
  56.      this package.
  57.  
  58.      First-time users entering the  ZipNews Door are prompted  to establish
  59.      their personal choices of archive utility and file transfer  protocol.
  60.      User choices are maintained for subsequent calls by the system.
  61.  
  62.      If download of a  news packet is requested,  the user is presented  an
  63.      active display indicating the newsgroups being scanned, the number  of
  64.      articles  being  extracted,  and  other  progress information.  At the
  65.      conclusion of the scan, the user  has the option of NOT accepting  the
  66.      packet and returning to the Waffle system to alter groups JOINed, etc.
  67.      Once the  user affirms  that an  assembled packet  should be sent, the
  68.      packet  is  compressed  and  the  transfer  of  the  resulting file is
  69.      initiated.  If the normal  process is interrupted before a  successful
  70.      conclusion, the "last article read"  pointers in the user's JOIN  file
  71.      are restored to their previous settings.  Otherwise, upon a successful
  72.      download,  these  pointers  are  appropriately  updated.  (Note:  this
  73.      operation  is  dependent  upon  the  archiver  and  protocol   modules
  74.      returning appropriate "success/fail" DOS ERRORLEVELs.  Utilities  such
  75.      as PKZIP and DSZ are known to work correctly in this regard.)
  76.  
  77.      ZipNews is SHARE-compatible and can support multi-node operations from
  78.      a single configuration file (ZN.CFG).  It can handle non-standard comm
  79.      port specifications and speeds  to 38,400 bps.   FOSSIL communications
  80.      are not used.   ZipNews disables  FOSSIL supported comm  when run, but
  81.      FOSSIL support is "reset" per the normal way when returning to Waffle.
  82.  
  83.      ZipNews  is  being  distributed  as  a  fully  functional package (not
  84.      crippled in any way).  In its unregistered form, ZipNews DOES  display
  85.      on-screen,  and  in  the  files  produced,  notices  informing  system
  86.      operators and users that it is an unregistered, evaluation copy.   The
  87.      executable  is  self-registering  in  that  when  a valid registration
  88.      number  is  input  these  notices  are  removed  and,  thereafter, the
  89.      registrant's name is displayed.
  90.  
  91.      The complete ZipNews v0.93ß package includes the following files:
  92.  
  93.                 ZIPNEWS.DOC  - this file
  94.                 ZN.COM       - executable module
  95.                 ZN.CFG       - sample ZipNews configuration file
  96.                 ZIPNEWS      - the Waffle external command file for ZipNews
  97.                 ZNORDER.FRM  - order form for registering ZipNews
  98.                 READ.ME      - quick review and features summary
  99.  
  100.                                  ZipNews v0.93ß                      Page 2
  101.      Description
  102.      -----------
  103.  
  104.      ZipNews is  designed for  operation on  MS-DOS 3.O  and later systems.
  105.      Operation with earlier DOS versions is not supported.
  106.  
  107.      ZipNews is distributed  as a small  .COM executable so  as to minimize
  108.      RAM requirements during operation (necessary, as it remains in  memory
  109.      when archiving utilities and protocol modules are invoked).
  110.  
  111.      It is being  released initially while  in its final  BETA test stages.
  112.      There may be a few minor additional features incorporated in the first
  113.      "official" release.  (See the READ.ME file included in this package.)
  114.  
  115.      Zipnews has been tested  primarily in a DOS  5.0/DESQview environment,
  116.      on a system running 4 nodes (PCBoard as primary BBS and Waffle 1.65 as
  117.      a Door).  It has not been tested with other versions of Waffle.
  118.  
  119.      Installation Overview
  120.      ---------------------
  121.  
  122.      This section quickly  suumarizes the major  steps in setting  up.  The
  123.      next section covers installation in greater detail.
  124.  
  125.      1. Place ZN.COM and the sample ZN.CFG into a directory in your PATH
  126.         (\waffle\bin will do quite nicely).
  127.      2. Customize ZN.CFG as needed using an ASCII text editor.  This also
  128.         involves naming and specifying command lines for archive utilities
  129.         and file tranfer protocols you wish to make available to callers.
  130.      3. Make (or modify) the ZIPNEWS external command file and place it in
  131.         your \waffle\external directory.
  132.      4. Provide for setting the required DOS ENVIRONMENT variables.  A very
  133.         important one is the DSZPORT variable.
  134.      5. If running a multi-node system, provide for uniquely named work
  135.         directories (one for each node) for temporary file storage.  This
  136.         will require an environment variable also.
  137.      6. If running a multi-node system, set the read-only (write protect)
  138.         file attribute bit on ZN.COM (avoids SHARE violations while
  139.         program loading during normal multi-node operations).
  140.  
  141.      Installation Details
  142.      --------------------
  143.      ZipNews (ZN.COM) should be placed in a directory contained in your DOS
  144.      PATH (e.g.,  \waffle\bin).   Your ZipNews  configuration file (ZN.CFG)
  145.      should be placed in the same directory.  WARNING:  ZN.COM locates  the
  146.      directory in which it resides, no matter how started, and you  MUST(!)
  147.      have ZN.CFG located in that same directory for proper operation.
  148.  
  149.      Your ZIPNEWS  external command  file should  be quite  similar to that
  150.      provided  as  part  of  this  package.    It  should be placed in your
  151.      \waffle\external directory (on Waffle  v1.65 systems).  An  example of
  152.      this one-line file appears below:
  153.  
  154.           zipnews /local /reset /command="d:\waffle\bin\zn %A"
  155.  
  156.      Note that the only command line parm required on startup is the Waffle
  157.      account (caller's ID).
  158.  
  159.                                  ZipNews v0.93ß                      Page 3
  160.  
  161.      To configure ZipNews to your system, use a standard ASCII text  editor
  162.      to modify the ZN.CFG provided.  The basic format rules are:
  163.  
  164.         1) Lines beginning with a space or a # symbol are ignored.
  165.         2) The 8 configuration subject titles listed below MUST be present
  166.            in the finished .CFG file and each must be followed by a
  167.            colon (:).  There MAY be intervening whitespace.
  168.  
  169.                newsgroups
  170.                user
  171.                temporary
  172.                bbs
  173.                abbrev
  174.                maximum
  175.                archivers
  176.                protocols
  177.  
  178.         3) The lines may be in any order, but the sub-lines for archivers
  179.            and protocols must be grouped within their respective sections,
  180.            and with the "prompt" lines immediately preceding the
  181.            corresponding command line specifications.
  182.         4) The command lines for the protocols contain one character in
  183.            the first position which is not a part of the command line.
  184.            This is the "selection character", that by which a caller may
  185.            express his/her protocol choice.
  186.  
  187.      Additional conventions used in the ZN.CFG file follow.
  188.  
  189.      If you need to specify more than one top level news directory on  your
  190.      system, indicate the  full pathname to  each (without a  trailing "\")
  191.      and with a space separating each pathname.
  192.  
  193.      If you have  sufficient RAM available  for use of  a RAMDISK, such  is
  194.      heartily recommended -- not only  for speed gains, but for  preventing
  195.      wear and tear on your hard drive.   However, you may name a hard  disk
  196.      and directory  in the  "temporary" parameter  as your  work directory.
  197.      This is the directory in which the extracted news articles are  placed
  198.      and compressed for download.  If you are running a multi-node  system,
  199.      you will need to specify multiple temporary work directories (one  for
  200.      each node) using this parameter . Here's how to do it:
  201.  
  202.         1) Set an ENVIRONMENT variable for each node.  In each node's
  203.            ENVIRONMENT a new variable should be defined, NODE, for example.
  204.            Assign the number of the node to each one as required.  Thus
  205.            in the ENVIRONMENT controlling node 1, you would set NODE=1,
  206.            for node 2, NODE=2 , etc.
  207.         2) Specify your "temporary" parameter such that it contains
  208.            the variable name with a % before and after it (just as in
  209.            DOS batch files).   So you might specify in your ZN.CFG line:
  210.  
  211.            temporary  :    g:\work%node%
  212.  
  213.            This would be interpreted by ZipNews running on node 1 as
  214.            g:\work1, on node 2 as g:\work2, etc.
  215.  
  216.      This method  will allow  you to  run any  number of  BBS nodes  from a
  217.      single copy of ZN.COM and ZN.CFG.
  218.  
  219.                                  ZipNews v0.93ß                      Page 4
  220.  
  221.      It is recommended  that Forsberg's ubiquitous  DSZ protocol module  be
  222.      used to support file transfers.  In fact, ZipNews has not been  tested
  223.      with any other.  Normally protocol modules must have the comm port and
  224.      speed communicated to them when invoked.  DSZ automatically determines
  225.      the speed, so this  spec is not necessary.   To specify the  comm port
  226.      number, or to  specify a non-standard  comm port, you  set the DSZPORT
  227.      environment variable.  (Set DSZPORT=1, for COM1:, for example.  Or for
  228.      a non-standard port at  hex address 3e8 and  using IRQ 5, it  would be
  229.      necessary to specify DSZPORT=3e8,5.  See DSZ docs for further info  as
  230.      necessary.)
  231.  
  232.      WARNING:  If  you do not  SET DSZPORT=SomeCommPort, ZipNews  will exit
  233.      with an error message.   The DSZPORT setting  is required even if  you
  234.      opt to use a different protocol module.
  235.  
  236.      (A future release of ZipNews may allow specification of port and speed
  237.      via substitutable parameters,  such as %1,  %2, etc.   If DSZ is  used
  238.      with  this  release,  however,  capability  for handling substitutable
  239.      parameters is not necessary.)
  240.  
  241.      Another required environment  variable for the  running of ZipNews  is
  242.      the WAFFLE variable.   But you're all using  that already, right?   :)
  243.      ZipNews requires that the WAFFLE variable be present, but the  present
  244.      release does not actually access your STATIC file.
  245.  
  246.      If you're running a multi-node system, there's one last step necessary
  247.      for reliable operations.  Switch to the directory in which you  placed
  248.      ZN.COM  and,  using  the  DOS  ATTRIB  command or other file attribute
  249.      setting/resetting utility, set the  READ ONLY attribute bit  ON (write
  250.      protect).  This will  prevent SHARE violations during  program loading
  251.      under normal multi-node operations.
  252.  
  253.      This completes the installation process.
  254.  
  255.      Operating/Using ZipNews
  256.      -----------------------
  257.  
  258.      There is not much more to say re:  operations; ... the first time  you
  259.      fire up ZipNews, it will be pretty obvious how it is used.  You should
  260.      know, however, about the local mode of operation.  Here is the command
  261.      syntax for ZipNews (excluding the registration function described
  262.      later):
  263.  
  264.                 zn WaffleAccount [local]
  265.  
  266.      If you specify  "local" after the  WaffleAccount, you may  operate the
  267.      package in a mode simulating that  of being online.  A ZipNews  packet
  268.      (not  compressed)  may  be  created  and  left  in  the work directory
  269.      (specified by  "temporary" in  the ZN.CFG  file).   This should  prove
  270.      helpful in testing parts of your setup.
  271.  
  272.      Re:  advising your users in use of the ZipNews door and its output  --
  273.      ZipNews' ASCII text  format can be  viewed quite conveniently  using a
  274.      text viewer such as Vern Buerg's LIST utility.  If, for example, you'd
  275.      like to quickly move from one  message to another, set LIST to  search
  276.      for "Subject:".  LIST nicely highlights the found line.  To search for
  277.      the next occurrence with  LIST, hit the "A"  key.  To quickly  scan to
  278.      reach the next newsgroup, use "* * <" as the search argument, etc.
  279.  
  280.                                  ZipNews v0.93ß                      Page 5
  281.  
  282.      Some of your callers might be confused as to what first to do with the
  283.      news packet received.  The source of confusion stems from the use of a
  284.      characteristic file extension of "ZNS" for the compressed news packet,
  285.      rather than ZIP or ARC, etc.  Most unarchiving utilities will work  on
  286.      a valid archive when supplied the  full filename and extension.  If  a
  287.      caller  has  a  ZipNews  packet  created  with PKZIP, for example, the
  288.      unarchiving command would be:
  289.  
  290.         PKUNZIP yourbbs.zns  (where "yourbbs" represents the name you have
  291.                                 selected for the "abbrev" parm in ZN.CFG)
  292.  
  293.      Distribution  and  Restrictions
  294.      -------------------------------
  295.  
  296.      ZipNews is made available to you as a fully functional package.  It is
  297.      distributed as SHAREWARE.   Should you  decide to use  ZipNews on your
  298.      system you are obliged  to register the product  for a fee of  $19.95.
  299.      Registered users are provided support via the BBS mentioned at the end
  300.      of this documentation OR via e-mail on the Internet.  You may use  the
  301.      form ZNORDER.FRM for registering your copy.
  302.  
  303.      You are welcome to distribute this package to others so long as it  is
  304.      unmodified and distributed in its entirety, and it is not included  or
  305.      bundled  with  other  goods  or  services  for which a fee is charged.
  306.      Exceptions are  that ZipNews  may be  distributed by  bulletin boards,
  307.      Internet archive sites, or other information services even though they
  308.      receive  fees  to  access  their  downloadable  files,  or  by library
  309.      services so long as the fee for the diskette on which this package  is
  310.      contained is not more than $6.50.
  311.  
  312.      Use  of  ZipNews  beyond  a  brief  evaluation  period by individuals,
  313.      business entities, corporations, and government agencies is prohibited
  314.      without payment of a registration fee of $19.95 per copy.
  315.  
  316.      After You Register ZipNews
  317.      --------------------------
  318.  
  319.      Once your registration and check have been received, you will be  sent
  320.      a  registration  number  (via  U.S.  mail  OR Internet e-mail, at your
  321.      option).  You may use this  number to convert to a registered  copy of
  322.      ZipNews which will  eliminate displays of  "unregistered", "evaluation
  323.      copy", etc., and it will insert  your name in displays and text  files
  324.      as having duly registered the product.
  325.  
  326.      To  make  a  registered  copy,  invoke  ZipNews  with the command line
  327.      parameter of --REGISTER, thusly:
  328.  
  329.          zn --register
  330.  
  331.      You are  prompted to  enter your  name and  your registration  number.
  332.      That's all there is to it.
  333.  
  334.      (IMPORTANT NOTE:   If  you are  running a  multi-node system  and have
  335.      followed the  suggestion of  setting the  file attribute  of ZN.COM to
  336.      READ ONLY,  you will  have to  set it  back to  normal before invoking
  337.      ZN.COM in registration mode.  Once you have completed the registration
  338.      procedure, you should set ZN.COM back to READ ONLY mode.)
  339.  
  340.                                  ZipNews v0.93ß                      Page 6
  341.  
  342.  
  343.      Support
  344.      -------
  345.  
  346.      Support is available to registered users of ZipNews primarily  through
  347.      the main message base of the Northern Lights BBS which can be  reached
  348.      at the number given below.
  349.  
  350.      Registration fees may be made payable to:
  351.  
  352.               J.C. Kilday Associates
  353.               P.O. Box 1961
  354.               Portland, ME 04104
  355.  
  356.      The author  may be  contacted at  the above  address, or  via Internet
  357.      e-mail (jkilday@nlbbs),  or through  the Northern  Lights BBS (address
  358.      messages to "Sysop")  at 207-761-4782.   The BBS operates  24 hours, 7
  359.      days.  Calls accepted at 14400 (v.32bis or VHST) or below.
  360.